home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1998 August / macformat-066.iso / Shareware Plus / Education / Twistory 1.0 PPC / instructions / Twistory Resources < prev   
Encoding:
Text File  |  1998-05-09  |  10.5 KB  |  239 lines  |  [TEXT/ttxt]
  1. Twistory 1.0 PPC
  2.  
  3. Table of Contents
  4.  
  5.    * Instructions
  6.  
  7.    * Resources
  8.  
  9.        1. About Resources
  10.        2. The File Mark-up: #file
  11.        3. The Place Mark-up: #c
  12.        4. The Era Mark-ups: #bc and #ad
  13.        5. The Person Mark-up: #p
  14.        6. The Event Mark-up: #e
  15.        7. The Sphere Mark-up: #s
  16.        8. Fields
  17.        9. Georef Format
  18.       10. Date Format
  19.  
  20. ----------------------------------------------------------------------------
  21.  
  22. About Resources
  23.  
  24.       Twistory comes with a folder of text resources called "ttt" and an
  25. index file called something like "index.ttt." When Twistory is first
  26. launched, you are presented with an "open dialog." Open the index file.
  27.  
  28.       The files in the "ttt" folder are of two types, identified by their
  29. filename extensions. The extension ".ttt" stands for "twistory text." These
  30. files contain information on places, people and events. There are also files
  31. with the extension ".geo" which are actually just ".ttt" files, but which
  32. are so named as a comment that they contain only place data. (You can
  33. actually call the files anything you want.)
  34.  
  35.       The other kind of file has the extension ".poly" for "polygon." These
  36. are also text files, but are most easily created and edited with a separate
  37. program called "PolyTool." They contain descriptions of closed or open
  38. polygons on the surface of the earth. Their vertex data is in minutes of
  39. latitude and longitude.
  40.  
  41.       The following sections describe the format of the ".ttt" files. The
  42. characters "#," "<" and ">" are reserved. They may only be used as
  43. documented below. "C++ and C-style" comments may also be used. You will see
  44. examples of these in the files.
  45.  
  46. The File Mark-up: #file
  47.  
  48.       Twistory files are arranged in a hierarchy, and this markup is used to
  49. link them together. An index file (which can have any name) is used to list
  50. all files or sub-index files. As Twistory reads any file, if it finds the
  51. sequence "#file" it suspends reading the file it is in and opens the file
  52. whose name appears after the "#file" markup. The format is as follows:
  53.  
  54. #file "ttt/egypt.ttt"
  55.  
  56. This tells Twistory to look in the folder "ttt" for a file called
  57. "egypt.ttt" and to read its data in right away.
  58.  
  59.       The order in which files are listed in the index, and the order in
  60. which items appear in the files, is significant. For example, a place
  61. description must be read in before it is referred to in a person record.
  62.  
  63. The Place Mark-up: #c
  64.  
  65.       The start of a place record is identified by the characters "#c". ("c"
  66. was chosen for "city," but regions of all size use the same format.) Here is
  67. a sample listing of four places:
  68.  
  69. #c <n>Canada<l>55N100W<rad>1200<nat>Canadian<col>100 60 80
  70. #c <n>Saskatchewan<l>54N106W<rad>400<sup>Canada
  71. #c <n>Ontario<l>49N83W<rad>600<sup>Canada
  72. #c <n>Toronto<l>4339N7920W<sup>Ontario
  73.  
  74. As you can see, places also have a hierarchy. When the map is at small
  75. scales, cities are not shown. An event occurring in Toronto would then
  76. appear next to the word "Ontario." At even smaller scales, events occurring
  77. in both Ontario and Saskatchewan would appear next to the word "Canada." The
  78. meaning of the individual fields are given below.
  79.  
  80. The Era Mark-ups: #bc and #ad
  81.  
  82.       These mark-ups have no fields, and are used to change the default era
  83. for dates.
  84.  
  85. A change in the default era made within a file is forgotten once that file
  86. ends and reading returns to a file which is higher up the hierarchy. But a
  87. change is passed down to a lower file. The safest practice is to specify
  88. either #bc or #ad at the beginning of every file.
  89.  
  90. The Person Mark-up: #p
  91.  
  92.       The start of a person record is identified by the characters "#p".
  93. Here is a sample listing of four persons:
  94.  
  95. #p <nat>British<o>king<n>George V<fa>Edward VII<b>1865 Jun 3<ac>1910 May 6<d>1936 Jan 20
  96. #p <nat>British<o>king<n>Edward VIII<fa>George V<b>1894 Jun 23<ac>1936 Jan 20<ab>1936 Dec 11<d>1972
  97. #p <nat>British<o>king<n>George VI<fa>George V<b>1895 Dec 14<ac>1936 Dec 11<d>1952 Feb 6
  98. #p <nat>British<o>queen<n>Elizabeth II<fa>George VI<b>1926 Apr 21<ac>1952 Feb 6
  99. #p <nat>British<o>prince<n>Charles<mo>Elizabeth II<b>1948 Nov 14
  100.  
  101. More information on the format and meaning of fields is given below.
  102.  
  103.       Family relations are described by the father (<fa>) and mother (<mo>)
  104. fields. The creation of the family tree in the genealogy views is dependent
  105. on those links being specified in the database. A person's database record
  106. may have his/her father and/or mother specified. The parents must then also
  107. be in the database, and must appear in the listing prior to their children.
  108.  
  109.       Children are specified only by their own links to their parents. This
  110. seems to be the simplest way to implement family relations in the database,
  111. since one may have many children, and several spouses, but one usually has
  112. unique parents. (In the case of adoption, often only one of the parents is a
  113. historical figure who would appear in the database.) Unions (marriages,
  114. etc.) do not appear in genealogy windows, but that may be an option in
  115. future. Relations other than parent-child cannot be specified directly; the
  116. intermediate person(s) must also be in the database. (For example, the
  117. relationship of uncle requires both the appropriate parent and grandparent
  118. to be in the database, in order for that relation to be revealed in some
  119. genealogy window.)
  120.  
  121. The Event Mark-up: #e
  122.  
  123.       The start of an event record is identified by the characters "#e".
  124. Here is a sample listing of events:
  125.  
  126. #bc
  127.  
  128. #e <t>battle<n>Fall of Jerusalem<d>586<c>Jerusalem<info>The city and the temple are destroyed
  129.  
  130. #ad
  131.  
  132. #e <t>use<n>decimal numbers in commerce<c>India<d>600
  133. #e <t>invent<au>Gutenberg<n>movable type<d>1456<c>Germany
  134. #e <t>wreck<n>The Vasa<d>1628 Aug 10
  135. #e <t>war<n>Third Anglo-Dutch War<d>1672<e>1674
  136. #e <t>extinct<n>Dodo<c>Mauritius<d>1681
  137.  
  138. The various fields are described below.
  139.  
  140. The Sphere Mark-up: #s
  141.  
  142.       The outline of a region such as an empire can be shown in the map view
  143. with a "sphere-of-influence" record. Here is an example:
  144.  
  145. #bc
  146. #s <n>Old Babylonian Empire<col>80 100 100<d>1800(100)<poly>"oldbab.poly"<e>1600(100)
  147.  
  148. The sample polygon has only one date interval, but it could have more. If
  149. you construct the polygons corresponding to the growth and decline of an
  150. empire, all of them can be linked into one sphere record by repeating the
  151. <d> and <poly> fields. Then end it with one <e> field. Information on these
  152. fields is found below.
  153.  
  154. Fields
  155.  
  156.       All of the information with a place, person, event, or sphere record
  157. is in the form of fields, which have a uniform format. They all begin with a
  158. field identifier between the characters < and >. Examples are seen above.
  159. The following table summarises them. Some fields, like the name, <n>, can be
  160. used with different types of records. Others can only be used with one type.
  161. The letters c, p, e, and s indicate which records they may be used with.
  162.  
  163. Mark-up  Description                       Applicability  Remarks
  164.  
  165. <n>      name                              c p e s
  166. <sup>    super-region (name of place)      c     s        used to link places into a hierarchy
  167. <aka>    alias or alternate name           c p
  168. <wat>    body of water                     c              boolean mark-up (no field following)
  169. <l>      location (georef)                 c              see below for format
  170. <adj>    national adjective                c              the name for a person who lives there
  171. <col>    colour                            c     s        The colour of a place is used in time-line bars.
  172. <sur>    surname                             p
  173. <nat>    nationality                         p            should match some region's <adj> field
  174. <fem>    female                              p            boolean mark-up (no field following)
  175. <o>      occupation                          p
  176. <b>      date of birth                       p            see below for format
  177. <d>      date of death                       p
  178. <fa>     father's name                       p
  179. <mo>     mother's name                       p
  180. <ma>     name of spouse                      p
  181. <ac>     date of accession                   p
  182. <ab>     date of abdication                  p
  183. <ap>     date of appointment of power        p
  184. <pow>    date of taking power                p
  185. <depo>   date of being deposed               p
  186. <el>     date of election to office          p
  187. <ret>    date of retirement from office      p
  188. <pro>    rank and date of promotion          p
  189. <c>      place link (name of place)          p e
  190. <dep>    date of departure                   p
  191. <arr>    date of arrival                     p
  192. <info>   additional information              p e
  193. <ref>    reference                           p e
  194. <d>      date                                  e s
  195. <e>      ending date                           e s
  196. <au>     link to author (name of person)       e
  197. <vic>    winning side of battle                e
  198. <poly>   polygon file name                       s
  199.  
  200. Georef Format
  201.  
  202.       Geographic References are given as the latitude and longitude
  203. concatenated together, in that order. Either one may be given in degrees, or
  204. degrees and minutes. Following the angle must appear one of the letters 'N'
  205. or 'S' for latitude, and 'E' or 'W' for longitude. NOTE: the degree part
  206. must consists of either 2 or 3 digits, not 1. If the angle is less than 10
  207. degrees, a leading zero must be used. (Otherwise, it would be ambiguous
  208. whether a three-digit angle was greater than 99 degrees and given in whole
  209. degrees, or an angle less than 10 degrees with minutes following.)
  210.  
  211. Date Format
  212.  
  213.       Dates are given in the format:
  214.  
  215. year number [ era ] [ month name [ date number ] ] [ (uncertainty) ]
  216.  
  217. The square brackets indicate optional parts. The year is the only mandatory
  218. element. It may be followed by either "A.D." or "B.C." to indicate an era
  219. other than the default; it is necessary to do this for lives or events which
  220. span the boundary between the B.C. and A.D. eras, since the default cannot
  221. be changed in mid-record.
  222.  
  223.       Following the year, the month name or its abbreviation (not number)
  224. may appear, if it is known. If the month is given, the date of the month may
  225. follow.
  226.  
  227.       Finally, an uncertainty may be given. There is already an implied
  228. uncertainty in any date that has only a year, or only year and month. For
  229. example, if only 1520 is stated, the actual date Twistory uses to draw the
  230. event is 1520 July 1, but the uncertainty will be plus or minus six months.
  231. To specify another uncertainty, put a number in round brackets following the
  232. date. (No spaces are necessary.) The units are those of the last element of
  233. the date. For example, 1889 May(3) means three month either side of 1889 May
  234. 15.
  235.  
  236. ----------------------------------------------------------------------------
  237.  
  238. Last modified on 1998 May 9
  239.